feat(instrument): Add --stub-wasi flag to replace WASI imports with stubs#104
Merged
lwshang merged 3 commits intodfinity:mainfrom Jan 27, 2026
Merged
feat(instrument): Add --stub-wasi flag to replace WASI imports with stubs#104lwshang merged 3 commits intodfinity:mainfrom
lwshang merged 3 commits intodfinity:mainfrom
Conversation
…tubs Problem: When using `ic-wasm instrument` on a canister WASM compiled with Emscripten, the resulting instrumented WASM contains WASI imports (fd_close, fd_write, fd_seek, etc.) that IC rejects at install time: Error: Wasm module has an invalid import section. Module imports function 'fd_close' from 'wasi_snapshot_preview1' that is not exported by the runtime. Solution: Add `--stub-wasi` flag that replaces WASI imports with local stub functions returning 0 (success) or trapping for proc_exit. This allows Emscripten- generated WASMs to be instrumented and deployed to IC. Usage: ic-wasm canister.wasm -o out.wasm instrument --stub-wasi
|
Dear @shogochiai, In order to potentially merge your code in this open-source repository and therefore proceed with your contribution, we need to have your approval on DFINITY's CLA. If you decide to agree with it, please visit this issue and read the instructions there. Once you have signed it, re-trigger the workflow on this PR to see if your code can be merged. — The DFINITY Foundation |
…ng vs WASI stubbing - Restructure Instrument section intro to list both capabilities - Add subsection headers: "Execution tracing" and "Stubbing WASI imports" - Move WASI stubbing docs to its own subsection after execution tracing - Update CHANGELOG with --stub-wasi flag addition Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
lwshang
approved these changes
Jan 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When using
ic-wasm instrumenton a canister WASM compiled with Emscripten, the resulting instrumented WASM contains WASI imports that IC rejects at install time:Use Case
For languages that compile through Emscripten/C (e.g., Idris2), WASI imports are introduced by the toolchain, not by user code. This flag provides a practical workaround until native WASM backends become available.
Solution
Add
--stub-wasiflag to theinstrumentsubcommand that replaces WASI imports with local stub functions:fd_closefd_writefd_readfd_seekenviron_sizes_getenviron_getproc_exitUsage
This is a workaround for edge cases (Emscripten, wasi-sdk).
The recommended approach is to build without WASI imports:
wasm32-unknown-unknowntarget with ic-cdkStub functions return success (0), which may hide real failures if your code actually depends on WASI functionality.
Test plan
stub_wasitest that verifies WASI imports are removedcargo clippyandcargo fmtpass🤖 Generated with Claude Code